W05-1. Docker Compose - 강의 노트

5주차 강의 노트: Docker Compose 로 웹 + DB 한 번에

이번 주 목표

  1. Compose 가 왜 필요한지, 무엇을 대신해 주는지 안다.
  2. compose.yaml 의 기본 구조(services, ports, environment, volumes, depends_on, healthcheck)를 읽고 쓸 수 있다.
  3. docker compose up / ps / logs / exec / down 으로 여러 컨테이너를 한 묶음으로 다룬다.
  4. 비밀번호 같은 값을 .env 파일로 분리한다.

진행: 이론 15분 (이 노트) → 실습 45분 (실습 가이드)

지난주 복습

  • Dockerfile 로 방명록 이미지 guestbook:v1, v2 를 만들고 Docker Hub 에 올렸다
  • 방명록은 DATABASE_URL 이 없으면 메모리에 저장 → 컨테이너를 지우면 글이 사라졌다


1. 왜 Compose 인가

3주차에 웹 + DB 를 띄우려면 이렇게 해야 했습니다.

docker network create study-net
docker volume create study-pgdata
docker run -d --name study-db --network study-net -e POSTGRES_PASSWORD=... -v study-pgdata:/var/lib/postgresql postgres:18-alpine
# (DB 가 준비될 때까지 기다렸다가)
docker run -d --name study-web --network study-net -p 8080:8000 -e DATABASE_URL=... guestbook:v1
문제 설명
명령이 길고 많다 옵션 하나만 틀려도 동작하지 않음
순서가 중요하다 네트워크 → DB → (기다림) → 웹
기록이 남지 않는다 어떤 옵션으로 띄웠는지 나중에 알기 어려움, 다른 사람에게 전달하기 어려움
정리가 귀찮다 컨테이너, 네트워크, 볼륨을 하나하나 지워야 함

Compose 의 해결책: 이 모든 설정을 compose.yaml 파일 하나에 적고, 명령 한 줄로 올리고 내립니다.

flowchart TB
    Y["📝 compose.yaml
(원하는 상태를 적은 파일)"] -- "docker compose up -d" --> R subgraph R["Compose 가 알아서 만드는 것"] N["네트워크
guestbook_default"] V["볼륨
guestbook_db-data"] W["web 컨테이너"] D["db 컨테이너"] end R -- "docker compose down" --> X["한 번에 정리"]
"명령" 에서 "선언" 으로

docker run 은 어떻게 할지(How) 를 하나하나 명령하는 방식입니다.
compose.yaml 은 원하는 상태(What) 를 적어 두는 방식입니다. "웹 1개, DB 1개, 이렇게 연결" 이라고 적으면 Compose 가 그 상태를 만듭니다.
6주차 Kubernetes 도 이 선언형 방식을 씁니다. Compose 는 그 연습입니다.


2. YAML 문법 3분 정리

compose.yaml 과 Kubernetes 설정 파일은 모두 YAML 형식입니다.

# 주석은 # 으로 시작
이름: 값                     # 키: 값 (콜론 뒤에 공백 필수)
목록:
  - 첫 번째                  # 목록은 "- " 로 시작
  - 두 번째
묶음:
  안쪽키: 값                 # 들여쓰기로 소속을 표현 (보통 공백 2칸)
  또다른키: 값
YAML 에서 가장 많이 하는 실수

  • 들여쓰기는 공백(스페이스)만 씁니다. 탭(Tab) 을 쓰면 에러가 납니다. VS Code 는 기본적으로 공백을 넣어 줍니다.
  • 같은 수준의 항목은 들여쓰기 칸 수가 똑같아야 합니다.
  • 키:값 처럼 콜론 뒤에 공백이 없으면 안 됩니다. 키: 값 으로 씁니다.
  • "8080:8000" 처럼 콜론이 들어간 값은 따옴표로 감쌉니다.


3. 오늘의 compose.yaml 읽기

services:                                # 띄울 컨테이너(서비스) 목록
  web:                                   # 서비스 이름 = 다른 컨테이너가 부를 때 쓰는 "주소"
    build: .                             # 이 폴더의 Dockerfile 로 이미지 빌드
    image: guestbook:compose             # 빌드한 이미지에 붙일 이름
    ports:
      - "8080:8000"                      # = docker run -p 8080:8000
    environment:                         # = docker run -e
      APP_VERSION: v1-compose
      DATABASE_URL: postgresql://guest:${DB_PASSWORD}@db:5432/guestbook
    depends_on:
      db:
        condition: service_healthy       # db 가 "healthy" 가 된 뒤에 web 시작
    restart: unless-stopped              # = docker run --restart unless-stopped

  db:
    image: postgres:18-alpine
    environment:
      POSTGRES_USER: guest
      POSTGRES_PASSWORD: ${DB_PASSWORD}  # .env 파일에서 값을 가져옴
      POSTGRES_DB: guestbook
    volumes:
      - db-data:/var/lib/postgresql      # = docker run -v (PostgreSQL 18 경로)
    healthcheck:                         # "준비됐는지" 확인하는 방법
      test: ["CMD-SHELL", "pg_isready -h localhost -U guest -d guestbook"]
      interval: 5s
      timeout: 3s
      retries: 10
    restart: unless-stopped

volumes:
  db-data:                               # 위에서 쓴 볼륨을 여기서 선언

YAML 은 줄 뒤에 붙인 # 도 주석입니다. Dockerfile 과 다르니 헷갈리지 마세요.

3-1. docker run 옵션과 1:1 대응

docker run compose.yaml
--name study-web services: 아래의 이름 (web)
-p 8080:8000 ports: - "8080:8000"
-e 이름=값 environment: 이름: 값
-v 볼륨:/경로 volumes: - 볼륨:/경로 (+ 맨 아래 volumes: 선언)
--network study-net 자동 (프로젝트마다 네트워크를 하나 만들어 모두 연결)
--restart unless-stopped restart: unless-stopped
docker build -t ... build: . + image: ...

3-2. 서비스 이름이 곧 주소

DATABASE_URL 의 @db:5432 를 보세요. db 는 서비스 이름입니다.
Compose 가 만든 네트워크에서는 3주차에 배운 Docker 내장 DNS 덕분에 서비스 이름으로 서로를 찾습니다.

3-3. depends_on + healthcheck: 기다렸다가 시작하기

설정 효과
depends_on: [db] (조건 없음) db 컨테이너가 시작되면 바로 web 시작. DB 가 아직 준비 중일 수 있음
depends_on: db: condition: service_healthy db 의 healthcheck 가 성공한 뒤에 web 시작 ✅
왜 pg_isready -h localhost 인가 (검증하다가 찾은 함정)

PostgreSQL 은 첫 실행 때 초기화를 위해 잠깐 임시 서버를 띄웁니다. 이 임시 서버는 외부(TCP) 접속을 받지 않습니다.
-h localhost 를 붙이면 TCP 로 접속해 보고 판단하므로, 임시 서버를 "준비 완료" 로 착각하지 않습니다.


4. .env: 비밀번호를 파일 밖으로

compose.yaml 에 ${DB_PASSWORD} 라고 쓰면, Compose 가 같은 폴더의 .env 파일에서 값을 찾아 넣습니다.

# .env
DB_PASSWORD=guestpw
파일 Git 에 올리나? 이유
compose.yaml ✅ 구조(설계도)는 팀이 공유
.env ❌ 비밀번호 등 환경마다 다르고 민감한 값
.env 는 이미지에도 들어가면 안 됩니다

.dockerignore 에 .env 를 추가해서, 빌드할 때 이미지 안으로 들어갈 가능성을 막습니다. 실습에서 직접 추가합니다.
이것은 연습용 방법입니다. 실무의 비밀 관리는 9주차 Kubernetes Secret 과 10주차에서 다룹니다.


5. 주요 명령어

모든 명령은 compose.yaml 이 있는 폴더에서 실행합니다.

명령 하는 일
docker compose config 파일 문법 검사 + .env 값이 채워진 최종 설정 보기
docker compose up -d 전부 만들고 백그라운드로 실행 (이미 있으면 바뀐 것만 다시 만듦)
docker compose up -d --build 이미지를 다시 빌드한 뒤 실행 (코드를 고쳤을 때)
docker compose ps 이 프로젝트의 컨테이너 상태
docker compose logs [-f] [서비스] 로그 보기 (서비스 이름을 주면 그것만)
docker compose exec 서비스 명령 실행 중인 서비스 안에서 명령 실행
docker compose down 컨테이너 + 네트워크 삭제. 볼륨(데이터)은 남김
docker compose down -v 볼륨까지 삭제 (데이터 영구 삭제!)
docker compose watch 코드를 저장하면 자동으로 컨테이너에 반영 (개발용)

이름 규칙

Compose 는 폴더 이름을 프로젝트 이름으로 씁니다. guestbook 폴더라면:

대상 이름
컨테이너 guestbook-web-1, guestbook-db-1 (프로젝트-서비스-번호)
네트워크 guestbook_default
볼륨 guestbook_db-data

6. Compose 의 한계 → Kubernetes 로

Compose 로 충분한 것 Compose 로 어려운 것
내 노트북에서 개발 환경 띄우기 서버 여러 대에 나눠 배포
테스트 환경, 소규모 서버 1대 서버가 죽으면 다른 서버에서 자동으로 다시 띄우기
팀원과 같은 환경 공유 트래픽에 따라 자동으로 늘리고 줄이기
같은 서비스 여러 개 앞에 로드밸런서 두기, 무중단 배포
실습에서 직접 확인합니다

docker compose up -d --scale web=3 으로 웹을 3개로 늘리면, 3개 모두 8080 포트를 쓰려다 충돌합니다.
"여러 개를 띄우고 그 앞에서 나눠 주는 일" 은 Kubernetes 의 Deployment + Service 가 해 줍니다(7~8주차).


핵심 요약

5주차 핵심
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
① Compose     여러 컨테이너 설정을 compose.yaml 하나에 "선언"
② 자동 처리    네트워크 자동 생성, 서비스 이름 = 주소 (web → db:5432)
③ 순서 보장    depends_on + condition: service_healthy + healthcheck
④ 비밀 분리    ${변수} ← .env 파일 (Git·이미지에 넣지 않기)
⑤ 명령        up -d [--build] / ps / logs -f / exec / down [-v]
⑥ 데이터       down 은 볼륨을 남기고, down -v 는 볼륨까지 지운다
⑦ 한계        서버 여러 대, 자동 복구, 오토스케일링 → Kubernetes

참고 자료

더 깊이 보고 싶다면 (볼트 내 정리 노트):

공식 문서:


네비게이션

이전 목록 다음
◀ 4주차 실습 목록으로 5주차 실습 ▶